Quarto Tutorial

Overview of Quarto

In brief, quarto is a powerful open-source tool for creating dynamic documents, reports, presentations, and websites using a simple markdown-based format. It is designed to facilitate reproducible research and data science workflows by allowing users to combine code, text, and visualizations in a single document. Some key features of quarto include:

Multi-language support: Quarto supports multiple programming languages, including R, Python, Julia, and JavaScript. This allows users to create documents that combine code from different languages seamlessly.
Reproducibility: Quarto enables users to create reproducible documents by embedding code chunks that can be executed to generate results and visualizations. This ensures that the document can be easily updated when the underlying data or analysis changes.

Anatomy of a Quarto (`.qmd`) Document

A quarto (.qmd) document typically consists of the following components:

YAML Front Matter: the document header
Code Chunks: code sections that can be executed within the document
Markdown Content: the main body (text) of the document

1. YAML Front Matter

The YAML front matter is a section at the top of the document that contains metadata about the document, such as the title, author, date, and output format. It is enclosed within triple dashes (---).

R
Python

Example YAML front matter:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format: html
---

Note: In order to preview or render a quarto document with R code, you need to have rmarkdown installed in your active R environment (via install.packages("rmarkdown")).

Example YAML front matter:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format: html
jupyter: python3
---

Note: In order to preview or render a quarto document with jupyter: python3, you need to have Jupyter/JupyterLab installed in your active Python environment. For example, if you are using conda, you should run conda install jupyter before rendering the document.

In this example, the YAML front matter specifies the title, author, date, and output format (HTML) of the document. You can change the output format to PDF, Word, and many other supported formats. For more details, see the Quarto Reference page.

Using R and Python in one quarto document

If you want to run both R and Python code chunks in the same document, do not include the jupyter: python3 line in the YAML front matter. Instead, you will need to install reticulate in R via: install.packages("reticulate").

Additional YAML Options

Some additional options you might find useful in the YAML front matter include:

---
title: "My Quarto Document"
author: "Your Name"
date: "Insert Date"
format:
  html:
    theme: sandstone # html theme
    toc: true # show table of contents
    lightbox: true # can click on images to enlarge
    code-fold: true # fold code chunks by default
    code-summary: "Show Code" # text for code fold button
execute:
  echo: true # show code output by default
  warning: false # suppress warnings output by default
  message: false # suppress messages output by default
---

These options and more can help customize the appearance of your quarto document (learn more here).

2. Code Chunks

Code chunks are sections of code that can be executed within the document. Code chunks are enclosed within triple backticks (```) and can specify the programming language used.

R
Python

Example R code chunk:

Show Code

x <- c(1, 2, 3)
y <- c(4, 5, 6)
plot(x, y)

Example Python code chunk:

Show Code

import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 6])
plt.show()

In these code chunks, we included chunk options (preceded by #|) to customize the output, such as figure labels, captions, and dimensions. For more details on chunk options, see these reference pages for Python and R.

Note that if you set jupyter: python3 in the YAML front matter, the fig-width and fig-height options are not supported; in order to change the figure size, you will need to do so within the code chunk itself (e.g., using plt.figure(figsize=(6,4)) in Python).

3. Markdown Content

Markdown content typically makes up the bulk of a quarto document. This is where you write the text, explanations, and narratives that accompany your code and results. Broadly speaking, Markdown is a lightweight markup language that allows you to format text using simple syntax.

Markdown Syntax	Output
`italics, bold, *bold italics*`	italics, bold, *bold italics*
`superscript^2^ / subscript~2~`	superscript² / subscript₂
`verbatim code`	`verbatim code`
`<https://quarto.org/>`	https://quarto.org/
`[Quarto](https://quarto.org)`	Quarto

Markdown Syntax	Output
`# Heading 1`	Heading 1
`## Heading 2`	Heading 2
`### Heading 3`	Heading 3
`#### Heading 4`	Heading 4

Markdown Syntax	Output
`- unordered list - sub-item 1 - sub-item 2 - sub-sub-item 1`	unordered list sub-item 1 sub-item 2 sub-sub-item 1
`1. ordered list 2. item 2 i) sub-item 1 A. sub-sub-item 1`	ordered list item 2 sub-item 1 sub-sub-item 1

Use $ delimiters for inline math and $$ delimiters for display math. For example:

Markdown Syntax Output

Markdown Syntax	Output
`inline math: $E = mc^{2}$`	inline math: \(E=mc^{2}\)
`display math: $$E = mc^{2}$$`	display math: \[E = mc^{2}\]

inline math: $E = mc^{2}$

inline math: $E=mc^{2}$

display math:

$$E = mc^{2}$$

display math:

\[E = mc^{2}\]

Markdown Syntax

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Output

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Learn more in the article on Callout Blocks.

You can create cross-references to figures, tables, sections, and equations using labels.

Markdown Syntax Output

Markdown Syntax	Output
`@fig-r`	Figure 1
`### Example Section {#sec-ex} @sec-ex`	Example Section Section 1.1.2

@fig-r

Figure 1

### Example Section {#sec-ex}
@sec-ex

Example Section

Section 1.1.2

Notes:

To reference a figure generated from a code chunk, you must include a label in the corresponding code chunk (e.g., #| label: fig-r in the R code chunk example above).
To reference a section, you must include a label in the section heading (e.g., {#sec-ex} in the section heading example above) and set number-sections: true in the YAML front matter so that the section numbers are generated.

More information on cross-references can be found here.

To see more examples of common markdown elements used in quarto documents, check out these resources:

Some additional quarto-specific features for enhancing your documents include:

Rendering Quarto Documents

Before rendering quarto documents, you must have the following packages installed in your active R/Python environment:

When using R only: rmarkdown
- Install via install.packages("rmarkdown") in your R console
When using Python only (with jupyter: python3 in YAML front matter): jupyter
- Install via conda install jupyter in your terminal
When using R and Python together: rmarkdown and reticulate
- Install via install.packages("rmarkdown") and install.packages("reticulate") in your R console

Now to render a quarto document into the desired output format (e.g., HTML, PDF, Word), you can use one of the following methods:

Command Line:

Open your terminal, navigate to the directory containing your .qmd file, and run the following command:
```
quarto render {your_document}.qmd
```
RStudio/Positron:

If you are using Positron (or RStudio or VS Code), you can click the “Preview” or “Render” button at the top of the editor window when you have your .qmd file open.

Additional Resources

For more information on using quarto, check out the following resources:

--- title: "Quarto Tutorial" format: html --- ## Overview of Quarto In brief, [**quarto**](https://quarto.org/) is a powerful open-source tool for creating dynamic documents, reports, presentations, and websites using a simple markdown-based format. It is designed to facilitate reproducible research and data science workflows by allowing users to combine code, text, and visualizations in a single document. Some key features of quarto include: - **Multi-language support**: Quarto supports multiple programming languages, including R, Python, Julia, and JavaScript. This allows users to create documents that combine code from different languages seamlessly. - **Reproducibility**: Quarto enables users to create reproducible documents by embedding code chunks that can be executed to generate results and visualizations. This ensures that the document can be easily updated when the underlying data or analysis changes. ## Anatomy of a Quarto (`.qmd`) Document A quarto (`.qmd`) document typically consists of the following components: 1. **YAML Front Matter**: the document header 2. **Code Chunks**: code sections that can be executed within the document 3. **Markdown Content**: the main body (text) of the document ### 1. YAML Front Matter {.unnumbered} The **YAML front matter** is a section at the top of the document that contains metadata about the document, such as the title, author, date, and output format. It is enclosed within triple dashes (`---`). ::: panel-tabset #### R {.unnumbered} Example YAML front matter: ```yaml --- title: "My Quarto Document" author: "Your Name" date: "Insert Date" format: html --- ``` *Note:* In order to preview or render a quarto document with R code, you need to have `rmarkdown` installed in your active R environment (via `install.packages("rmarkdown")`). #### Python {.unnumbered} Example YAML front matter: ```yaml --- title: "My Quarto Document" author: "Your Name" date: "Insert Date" format: html jupyter: python3 --- ``` *Note:* In order to preview or render a quarto document with `jupyter: python3`, you need to have Jupyter/JupyterLab installed in your active Python environment. For example, if you are using `conda`, you should run `conda install jupyter` before rendering the document. ::: In this example, the YAML front matter specifies the title, author, date, and output format (HTML) of the document. You can change the output format to PDF, Word, and many other supported formats. For more details, see the [Quarto Reference](https://quarto.org/docs/reference/) page. ::: {.callout-warning title="Using R and Python in one quarto document" collapse="true"} If you want to run both R and Python code chunks in the same document, do not include the `jupyter: python3` line in the YAML front matter. Instead, you will need to install `reticulate` in R via: `install.packages("reticulate")`. ::: ::: {.callout-note title="Additional YAML Options" collapse="true"} Some additional options you might find useful in the YAML front matter include: ```yaml --- title: "My Quarto Document" author: "Your Name" date: "Insert Date" format: html: theme: sandstone # html theme toc: true # show table of contents lightbox: true # can click on images to enlarge code-fold: true # fold code chunks by default code-summary: "Show Code" # text for code fold button execute: echo: true # show code output by default warning: false # suppress warnings output by default message: false # suppress messages output by default --- ``` These options and more can help customize the appearance of your quarto document (learn more [here](https://quarto.org/docs/get-started/hello/rstudio.html#yaml-header)). ::: ### 2. Code Chunks {.unnumbered} **Code chunks** are sections of code that can be executed within the document. Code chunks are enclosed within triple backticks (```) and can specify the programming language used. ::: panel-tabset #### R {.unnumbered} Example R code chunk: ```{r} #| label: fig-r #| fig-cap: "An example plot in R" #| fig-width: 6 #| fig-height: 4 x <- c(1, 2, 3) y <- c(4, 5, 6) plot(x, y) ``` #### Python {.unnumbered} Example Python code chunk: ```{python} #| label: fig-python #| fig-cap: "An example plot in Python" #| fig-width: 6 #| fig-height: 4 import matplotlib.pyplot as plt plt.plot([1, 2, 3], [4, 5, 6]) plt.show() ``` ::: In these code chunks, we included *chunk options* (preceded by `#|`) to customize the output, such as figure labels, captions, and dimensions. For more details on chunk options, see these reference pages for [Python](https://quarto.org/docs/reference/cells/cells-jupyter.html) and [R](https://quarto.org/docs/reference/cells/cells-knitr.html). Note that if you set `jupyter: python3` in the YAML front matter, the `fig-width` and `fig-height` options are not supported; in order to change the figure size, you will need to do so within the code chunk itself (e.g., using `plt.figure(figsize=(6,4))` in Python). ### 3. Markdown Content {.unnumbered} **Markdown content** typically makes up the bulk of a quarto document. This is where you write the text, explanations, and narratives that accompany your code and results. Broadly speaking, Markdown is a lightweight markup language that allows you to format text using simple syntax. ::: panel-tabset #### Text Formatting {.unnumbered} +-----------------------------------------+-----------------------------------------+ | Markdown Syntax | Output | +=========================================+=========================================+ | ``` markdown | *italics*, **bold**, ***bold italics*** | | *italics*, **bold**, ***bold italics*** | | | ``` | | +-----------------------------------------+-----------------------------------------+ | ``` markdown | superscript^2^ / subscript~2~ | | superscript^2^ / subscript~2~ | | | ``` | | +-----------------------------------------+-----------------------------------------+ | ``` markdown | `verbatim code` | | `verbatim code` | | | ``` | | +-----------------------------------------+-----------------------------------------+ | ``` markdown | <https://quarto.org/> | | <https://quarto.org/> | | | ``` | | +-----------------------------------------+-----------------------------------------+ | ``` markdown | [Quarto](https://quarto.org) | | [Quarto](https://quarto.org) | | | ``` | | +-----------------------------------------+-----------------------------------------+ #### Section Headings {.unnumbered} +------------------+-----------------------------------+ | Markdown Syntax | Output | +==================+===================================+ | ``` markdown | # Heading 1 | | # Heading 1 | | | ``` | | +------------------+-----------------------------------+ | ``` markdown | ## Heading 2 | | ## Heading 2 | | | ``` | | +------------------+-----------------------------------+ | ``` markdown | ### Heading 3 | | ### Heading 3 | | | ``` | | +------------------+-----------------------------------+ | ``` markdown | #### Heading 4 | | #### Heading 4 | | | ``` | | +------------------+-----------------------------------+ #### Lists {.unnumbered} +-----------------------------------+---------------------------------+ | Markdown Syntax | Output | +===================================+=================================+ | ``` markdown | | | - unordered list | - unordered list | | - sub-item 1 | - sub-item 1 | | - sub-item 2 | - sub-item 2 | | - sub-sub-item 1 | - sub-sub-item 1 | | ``` | | +-----------------------------------+---------------------------------+ | ``` markdown | | | 1. ordered list | 1. ordered list | | 2. item 2 | 2. item 2 | | i) sub-item 1 | i) sub-item 1 | | A. sub-sub-item 1 | A. sub-sub-item 1 | | ``` | | +-----------------------------------+---------------------------------+ #### Equations {.unnumbered} Use `$` delimiters for inline math and `$$` delimiters for display math. For example: +---------------------------+-------------------------+ | Markdown Syntax | Output | +===========================+=========================+ | ``` markdown | | | inline math: $E = mc^{2}$ | inline math: $E=mc^{2}$ | | ``` | | +---------------------------+-------------------------+ | ``` markdown | | | display math: | display math: | | | | | $$E = mc^{2}$$ | $$E = mc^{2}$$ | | ``` | | +---------------------------+-------------------------+ #### Callout Blocks {.unnumbered} ##### Markdown Syntax {.unnumbered} ``` markdown :::{.callout-note} Note that there are five types of callouts, including: `note`, `tip`, `warning`, `caution`, and `important`. ::: ``` ##### Output {.unnumbered} ::: callout-note Note that there are five types of callouts, including `note`, `tip`, `warning`, `caution`, and `important`. ::: Learn more in the article on [Callout Blocks](https://quarto.org/docs/authoring/callouts.html). #### Cross-References {.unnumbered} You can create cross-references to figures, tables, sections, and equations using labels. +-------------------------------+-------------------------------+ | Markdown Syntax | Output | +===============================+===============================+ | ``` markdown | | | @fig-r | @fig-r | | ``` | | +-------------------------------+-------------------------------+ | ``` markdown | | | ### Example Section {#sec-ex} | ### Example Section {#sec-ex} | | @sec-ex | @sec-ex | | ``` | | +-------------------------------+-------------------------------+ *Notes:* - To reference a figure generated from a code chunk, you must include a label in the corresponding code chunk (e.g., `#| label: fig-r` in the R code chunk example above). - To reference a section, you must include a label in the section heading (e.g., `{#sec-ex}` in the section heading example above) and set `number-sections: true` in the YAML front matter so that the section numbers are generated. More information on cross-references can be found [here](https://quarto.org/docs/authoring/cross-references.html). ::: To see more examples of common markdown elements used in quarto documents, check out these resources: - [Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html) - [Figures](https://quarto.org/docs/authoring/figures.html) - [Tables](https://quarto.org/docs/authoring/tables.html) - [Bibliographies](https://quarto.org/docs/authoring/citations.html) Some additional quarto-specific features for enhancing your documents include: - [Panels and Tabsets](https://quarto.org/docs/output-formats/html-basics.html#tabsets) - [HTML Basics](https://quarto.org/docs/output-formats/html-basics.html) ## Rendering Quarto Documents Before rendering quarto documents, you must have the following packages installed in your active R/Python environment: - When using **R** only: `rmarkdown` - Install via `install.packages("rmarkdown")` in your R console - When using **Python** only (with `jupyter: python3` in YAML front matter): `jupyter` - Install via `conda install jupyter` in your terminal - When using **R** and **Python** together: `rmarkdown` and `reticulate` - Install via `install.packages("rmarkdown")` and `install.packages("reticulate")` in your R console Now to render a quarto document into the desired output format (e.g., HTML, PDF, Word), you can use one of the following methods: 1. **Command Line**: Open your terminal, navigate to the directory containing your `.qmd` file, and run the following command: ```bash quarto render {your_document}.qmd ``` 2. **RStudio/Positron**: If you are using Positron (or RStudio or VS Code), you can click the "Preview" or "Render" button at the top of the editor window when you have your `.qmd` file open. ## Additional Resources For more information on using quarto, check out the following resources: - [Quarto Official Website](https://quarto.org/) - [Quarto Gallery](https://quarto.org/docs/gallery/)

Overview of Quarto

Anatomy of a Quarto (.qmd) Document

1. YAML Front Matter

2. Code Chunks

3. Markdown Content

Heading 1

Heading 2

Heading 3

Heading 4